The JavaScript API

The JavaScript programming language was developed by Netscape Communications, and is documented in references listed in Appendix B of The VRML 2.0 Sourcebook.

When JavaScript program scripts are used, the MIME type must be application/x-javascript, and the file name extension must be ".js". For example, the following Script node references a JavaScript file using the url field:

Script {
        url "Example.js"
        eventIn SFFloat set_fraction
        eventOut SFFloat value_changed
}

The JavaScript API (Application Programming Interface) provides features grouped into the following categories and discussed in the next few sections:

• Features to access the interface fields and eventOuts of the program script's Script node. In JavaScript, these features are provided by interface variables automatically provided to the program script.
• Features to convert values between JavaScript's data types, and those of VRML. In JavaScript, these features are provided by automatic data type conversion built into the language.
• Functions to handle initialization, shutdown, and event delivery. In JavaScript, these functions are provided by the Script node's program script.
• Methods to access features of the browser, including changing the current world, and loading new worlds. In JavaScript, these methods are provided by the browser object, automatically provided to the program script.

Accessing Interface Fields and EventOuts

Each interface field and eventOut in the Script node has a corresponding global interface variable of the same name, and automatically declared for the JavaScript program script.

• Reading from or writing to an interface field's interface variable reads or writes the field's value.
• Reading from an interface eventOut's interface variable reads the last value sent using that eventOut.
• Writing to an interface eventOut's interface variable sends the written value as an event. The time stamp for the event depends upon the function executing. The event is sent upon completion of the currently executing function. Assignment to the same eventOut interface variable multiple times during one execution of the function only sends one event, and that event contains the last value assigned to the interface variable.

Converting Between Data Types

VRML data types for interface fields, eventIns, and eventOuts are automatically mapped to equivalent JavaScript data types, as indicated in the following table:

VRML Data Type	JavaScript Type
SFBool	boolean
SFColor/MFColor	array of numbers
SFFloat/MFFloat	number or array of numbers
SFImage	array of numbers
SFInt32/MFInt32	number or array of numbers
SFNode/MFNode	object or array of objects
SFRotation/MFRotation	array of numbers
SFString/MFString	string or array of strings
SFTime	number
SFVec2f/MFVec2f	array of numbers
SFVec3f/MFVec3f	array of numbers

Multi-Value VRML data types, such as those with "MF" data type prefix, are treated as one-dimensional arrays in JavaScript. The first value in the data type's list of values is available in the first array location, the second in the second array location, and so forth. Array indexing starts at 0 for the first value.

Multi-Component VRML data types, such as the vector and color data types, are treated as one-dimensional arrays in JavaScript. The first component of the value is available in the first array location, the second in the second array location, and so forth.

Multi-Value Multi-Component VRML data types, such as lists of vectors and colors, are treated as two-dimensional arrays in JavaScript. Values are stored in row-major order, so that the right-most index, in a two-dimensional array reference, selects the component, and the left-most index selects the entry in the value list.

The Node Object

The SFNode VRML data type is treated as a node object in JavaScript. The MFNode VRML data type is treated as an array of node objects. Each node object has one property for each exposed field, eventIn, or eventOut for the node. Property names match those for the corresponding exposed field, eventIn, or eventOut.

If the value of the program script's Script node directOutput field is FALSE:

• Reading from a node object's exposed field property reads the field's value.
• Reading from a node object's eventOut property reads the last value sent using that eventOut.
• No other read or write operations are allowed when the directOutput field value is FALSE.

Otherwise, when the directOutput field value is TRUE:

• All operations available when the directOutput field value is FALSE are also supported when the field value is TRUE.
• Writing to a node object's exposed field property writes the field's value.
• Writing to a node object's eventIn property sends the written value as an event to the node. The time stamp for the event depends upon the function executing. The event is sent upon completion of the currently executing function. Assignment to the same eventIn property multiple times during one execution of the function only sends one event, and that event contains the last value assigned to the eventIn property.

Delivering Events

Program script functions are called by the browser upon initialization, shutdown, and event receipt. In the function listings below, the data type for each method argument (if any) is indicated in italics preceding the name of the argument. The data type is for informational purposes only and is not typed in when writing program scripts.

function initialize( )

The initialize function is called when the program script is loaded and before delivery of any events to the program script. The initialize function is optional and may be omitted if there is no need for initialization actions. Events generated by the function are time stamped with the absolute time at which the program script was loaded.

function shutdown( )

The shutdown function is called when the program script is about to be deleted. The shutdown function is optional and may be omitted if there is no need for shutdown actions. Events generated by the function are time stamped with the absolute time at which the program script's Script node was deleted.

function eventInName( dataType eventValue, number eventTime )

Each interface eventIn defined in the program script's Script node must have a corresponding function with the same name. The eventIn function is called when a new event is available for the node's eventIn. The value of the eventValue argument is the value of the incoming event. The eventValue argument has a JavaScript data type corresponding to the VRML data type for the eventIn. The value of the eventTime argument is the time stamp of the incoming event. The time stamp has a numeric JavaScript data type and stores a double-precision floating-point number for the absolute time at which the event was created. Events generated by the function are time stamped with the absolute time value of the eventTime argument.

function eventsProcessed( )

The eventsProcessed function is called upon completion of processing one or more pending events for the program script. Events generated by the function are time stamped with the absolute time value of the last event processed before calling the eventsProcessed function.

Accessing the Browser

The browser object is automatically made available to the program script and provides methods for getting browser information, changing world content, and loading world content. In these listings, the JavaScript data type for each method argument and return value is indicated in italics preceding the name of the argument or return value. The data type is for informational purposes only and is not typed in when writing program scripts.

number frameRate = getCurrentFrameRate( )

The getCurrentFrameRate method returns the current drawing frame rate, measured in frames per second. If the frame rate cannot be determined, or the VRML browser does not support frame rate computation, a 0.0 is returned.

number moveSpeed = getCurrentSpeed( )

The getCurrentSpeed method returns the current movement speed of the viewer, measured in units per second. If the speed cannot be determined, is not meaningful for the current navigation type, or the VRML browser does not support movement speed computation, a 0.0 is returned.

string name = browser.getName( )

The getName method returns the name of the VRML browser currently in use. The format of the browser name is browser-dependent. If the browser name cannot be determined, or the VRML browser does not support returning a browser name, an empty string is returned.

string url = getWorldURL( )

The getWorldURL method returns the URL for the currently loaded world. If the world includes inlined files, the returned URL is that of the top-most world from which everything else is inlined.

stringversion = browser.getVersion( )

The getVersion method returns a version name for the VRML browser currently in use. The format of the version name is browser-dependent. If the browser name cannot be determined, or the VRML browser does not support returning a browser name, an empty string is returned.

addRoute( node object fromNode, string fromEventOut, node object toNode, string toEventIn )

The addRoute method creates a new route from the node indicated in the fromNode argument, to the node indicated in the toNode argument. The route connects the eventOut selected in the fromEventOut argument to the eventIn selected in the toEventIn argument.

node object array newWorld = createVrmlFromString( string vrmlSyntax )

The createVrmlFromString method creates a new world, or portion of a world, using the VRML syntax contained within the vrmlSyntax argument. The vrmlSyntax argument value may contain any node descriptions, exactly as they might occur in a VRML file. The returned list of node objects may be added to the current world, or used to replace the current world by using the replaceWorld method.

createVrmlFromUrl( string array url, node object receiverNode, string eventInName )

The createVrmlFromUrl method creates a new world, or portion of a world, by loading a VRML file using the list of URLs in the url argument. The value of the url argument specifies a prioritized list of URLs for a world to load, ordered from highest priority to lowest. The VRML browser starts by trying to open the world specified by the first URL in the list. If the world cannot be found, the browser tries the second URL in the list, and so on. When a URL is found that indicates a world that can be opened, the world is loaded into the browser. If none of the URLs can be opened, then no world is loaded and the browser may alert the viewer that an error has occurred. When the world, or part of a world, is loaded, an event is sent to a receiver node. The receiver node is indicated by the value of the receiverNode argument. The name of the eventIn function to be called is indicated by the value of the eventInName argument. When the receiver node's eventIn function is called, the event value is a list of node objects for the new world, or portion of a world. The event's list of node objects may be added to the current world, or used to replace the current world by using the replaceWorld method.

deleteRoute( node object fromNode, string fromEventOut, node object toNode, string toEventIn )

The deleteRoute method removes an existing route from the node indicated in the fromNode argument, to the node indicated in the toNode argument. The method disconnects the route from the eventOut selected in the fromEventOut argument to the eventIn selected in the toEventIn argument.

setDescription( string description )

The setDescription method replaces the current text description of the world with the text in the description argument. Most browsers display the description in the window title bar for the browser.

loadURL( string url, string array parameters )

The loadURL method loads a world using the list of URLs in the url argument and the list of parameters in the parameters argument. Depending upon the parameters, the loaded world may replace the current world, causing all shapes in the current world to be deleted, and all current program scripts to be shut down. The value of the url argument specifies a prioritized list of URLs for a world to load, ordered from highest priority to lowest. The VRML browser starts by trying to open the world specified by the first URL in the list. If the world cannot be found, the browser tries the second URL in the list, and so on. When a URL is found that indicates a world that can be opened, the world is loaded into the browser. If none of the URLs can be opened, then no world is loaded and the browser may alert the viewer that an error has occurred. The value of the parameters argument specifies optional browser parameters that control how the new world is loaded. Parameters argument values are the same as discussed in Chapter XX for the Anchor node. In one use, the parameters argument value may select a target frame in the browser as the destination of the loaded world. If that target frame is the same as the frame containing the current world, then the current world is replaced by the new world. This method returns immediately.

loadWorld( string array url )

Similar to the loadURL method, the loadWorld method loads a world using the list of URLs in the url argument. The loaded world always replaces the current world, causing all shapes in the current world to be deleted, and all current program scripts to be shut down. The value of the url argument specifies a prioritized list of URLs for a world to load, ordered from highest priority to lowest. The VRML browser starts by trying to open the world specified by the first URL in the list. If the world cannot be found, the browser tries the second URL in the list, and so on. When a URL is found that indicates a world that can be opened, the world is loaded into the browser. If none of the URLs can be opened, then no world is loaded and the browser may alert the viewer that an error has occurred. This method may not return, since the world containing the calling program script is replaced by the new world loaded from the URL.

replaceWorld( node object array newWorld )

The replaceWorld method replaces the current world with the list of nodes in the newWorld argument. All shapes in the current world are deleted, and all current program scripts are shut down. This method may not return, since the world containing the calling program script is replaced by the new world.